package com.ruoyi.campus.service;

import org.springframework.web.multipart.MultipartFile;

import javax.servlet.http.HttpServletResponse;
import java.util.List;
import java.util.Map;

/**
 * 文件存储Service接口
 * 
 * @author campus-alarm
 * @date 2024-01-01
 */
public interface IFileStorageService
{
    /**
     * 上传文件
     * 
     * @param file 文件
     * @param folder 文件夹
     * @return 上传结果
     */
    Map<String, Object> uploadFile(MultipartFile file, String folder) throws Exception;

    /**
     * 初始化分片上传
     * 
     * @param fileName 文件名
     * @param fileSize 文件大小
     * @param chunkSize 分片大小
     * @param folder 文件夹
     * @return 初始化结果
     */
    Map<String, Object> initChunkUpload(String fileName, Long fileSize, Integer chunkSize, String folder) throws Exception;

    /**
     * 上传分片
     * 
     * @param chunk 分片文件
     * @param uploadId 上传ID
     * @param chunkIndex 分片索引
     * @return 上传结果
     */
    Map<String, Object> uploadChunk(MultipartFile chunk, String uploadId, Integer chunkIndex) throws Exception;

    /**
     * 合并分片文件
     * 
     * @param uploadId 上传ID
     * @param totalChunks 总分片数
     * @return 合并结果
     */
    Map<String, Object> mergeChunks(String uploadId, Integer totalChunks) throws Exception;

    /**
     * 删除文件
     * 
     * @param filePath 文件路径
     * @return 是否成功
     */
    boolean deleteFile(String filePath) throws Exception;

    /**
     * 批量删除文件
     * 
     * @param filePaths 文件路径列表
     * @return 删除结果
     */
    Map<String, Boolean> deleteFiles(List<String> filePaths) throws Exception;

    /**
     * 下载文件
     * 
     * @param filePath 文件路径
     * @param response 响应对象
     */
    void downloadFile(String filePath, HttpServletResponse response) throws Exception;

    /**
     * 获取文件信息
     * 
     * @param filePath 文件路径
     * @return 文件信息
     */
    Map<String, Object> getFileInfo(String filePath) throws Exception;

    /**
     * 生成文件访问URL
     * 
     * @param filePath 文件路径
     * @return 访问URL
     */
    String generateFileUrl(String filePath);

    /**
     * 生成预签名上传URL（用于前端直传）
     * 
     * @param fileName 文件名
     * @param folder 文件夹
     * @param expireTime 过期时间（秒）
     * @return 预签名URL
     */
    Map<String, Object> generatePresignedUploadUrl(String fileName, String folder, Integer expireTime) throws Exception;

    /**
     * 复制文件
     * 
     * @param sourcePath 源文件路径
     * @param targetPath 目标文件路径
     * @return 是否成功
     */
    boolean copyFile(String sourcePath, String targetPath) throws Exception;

    /**
     * 移动文件
     * 
     * @param sourcePath 源文件路径
     * @param targetPath 目标文件路径
     * @return 是否成功
     */
    boolean moveFile(String sourcePath, String targetPath) throws Exception;

    /**
     * 检查文件是否存在
     * 
     * @param filePath 文件路径
     * @return 是否存在
     */
    boolean fileExists(String filePath) throws Exception;

    /**
     * 获取文件列表
     * 
     * @param folder 文件夹
     * @param recursive 是否递归
     * @return 文件列表
     */
    List<Map<String, Object>> listFiles(String folder, boolean recursive) throws Exception;

    /**
     * 清理临时文件
     * 
     * @param beforeTime 清理时间之前的文件
     * @return 清理数量
     */
    int cleanupTempFiles(long beforeTime) throws Exception;
} 